<html>
<head>
<title>SWT Data Bindings</title>
<meta content="text/html; charset=windows-1252" http-equiv="Content-Type">
<link href="../../../../book.css" rel="stylesheet" type="text/css">
</head>
<body bgcolor="#FFFFFF">
    <h1>SWT Data Bindings</h1>
	<h3>Supported for Eclipse 3.3 
	and above only</h3>
	<p class="pnoall">Click the
	<b>Bindings</b> tab in the editor to created and edit 
	data bindings.</p>
	<p class="pnoall">
	<img border="0" src="../../../wizards/databinding/images/data_binding_tab.gif" align="absbottom"></p>
	<p class="pnoall">
	<img border="0" src="images/data_binding_swt1.gif"></p>
	<p class="pnoall">SWT uses simple bindings between targets and models. </p>
	<h2>Target &amp; Model Types</h2>
	<p class="pnoall">Two types of targets and models are supported:</p>
	<ul>
		<li>
		<p class="pnoall"><b>
		<img border="0" src="images/data_binding_beans_button.gif" align="absbottom"> 
		Beans</b>: any field of the current compilation unit may be selected. 
		The filter field above the list can be used to filter the list of beans. 
		The
		<img border="0" src="images/clear_filter_button.gif" width="23" height="22" align="absbottom"> 
		clear button can be used to clear the filter and restore the full list.
		<b>Beans</b> are the primary data source for bindings (usually the 
		model). Any property of the <b>Bean</b> may be observed. Individual 
		beans may also be expanded to reveal their direct sub properties.<br>
		<br>
		<img border="0" src="images/model_beans.gif">&nbsp;&nbsp;&nbsp;
		<img border="0" src="images/model_beans_filtered.gif" align="top">&nbsp;&nbsp;&nbsp;
		<img border="0" src="images/model_beans_expanded.gif" width="230" height="322" align="top"><br>
&nbsp;</li>
		<li>
		<p class="pnoall"><b>
		<img border="0" src="images/data_binding_widgets_button.gif" width="23" height="22" align="absbottom"> 
		Widgets</b>: any widget or JFace viewer in the current compilation unit may be selected. 
		If a widget is not a field, it will be converted to a field 
		automatically. The filter field above the list can be used to filter the 
		list of widgets. The
		<img border="0" src="images/clear_filter_button.gif" width="23" height="22" align="absbottom"> 
		clear button can be used to clear the filter and restore the full list. 
		Only the following predefined SWT control properties may be observed: <b>
		enabled</b>, <b>visible</b>, <b>toolTipText</b>, <b>selection</b>, <b>
		min</b>, <b>max</b>, <b>text</b>, <b>items</b>,<b> selectionIndex</b>,
		<b>foreground</b>, <b>background</b>, <b>font</b> and <b>editable</b>. 
		Any JFace viewer with a <b>selection</b> 
		property of type <b>org.eclipse.jface.viewers.IStructuredSelection</b> 
		may be selected. If the selection contains a Java Bean, it can be bound 
		to another object as either target or source. Typically, the selection 
		of one viewer is bound to the input of another viewer in a master-detail 
		relationship. If a selection is not a field, it will be converted to a 
		field automatically<br>
		<br>
		<img border="0" src="images/target_widgets.gif">&nbsp;&nbsp;&nbsp;&nbsp;
		<img border="0" src="images/target_widgets_filtered.gif" align="top"></li>
	</ul>
	<h2>Properties</h2>
	<p class="pnoall">When any <b>Target</b> or <b>Model</b> object is selected, 
	its properties (bean fields or predefined SWT widget properties) are shown 
	in the associated <b>Properties</b> list. A drop down filter menu is 
	available to filter the Property list by type. Supported filters are <b>
	String</b>, <b>Boolean</b>, <b>Numbers</b>, <b>Color</b> and <b>Font</b>.</p>
	<p class="pnoall">
	<img border="0" src="images/properties.gif">&nbsp;&nbsp; &nbsp;
	<img border="0" src="images/properties_filtered.gif">&nbsp;&nbsp; &nbsp;
	<img border="0" src="images/filter_button.gif" align="top"></p>
	<p class="pnoall">
	If the model object is another binding object, it is possible to bind to the 
	validation status. If the object is already an <b>IObservableValue</b> (like 
	a <b>WritableValue</b>), it can be bound to directly.</p>
	<p class="pnoall">
	<img border="0" src="images/validation_status.gif">&nbsp;&nbsp;
	<img border="0" src="images/observable_value.gif" align="top"></p>
	<h2>New SWT Bindings</h2>
	<p class="pnoall">New bindings are created by selecting a <b>Target</b>, a
	<b>Target Property</b>, a <b>Source</b>, a <b>Source Property</b> and 
	clicking the
	<img border="0" src="images/binding_button.gif" width="26" height="24" align="absbottom">
	<b>Bind</b> button. When creating a binding, the update strategy from <b>
	target to model</b> and <b>model to target</b> may be specified as well as 
	any strategy-specific properties (validators and converters). </p>
	<p class="pnoall">
	<img border="0" src="images/bind_properties_swt1.gif" align="top"></p>
	<p class="pnoall">When the Target or Model is a Text widget and the text 
	property is selected, the triggering event may be specified as <b>SWT.Modify</b>,
	<b>SWT.FocusOut</b> or <b>SWT.NONE</b>.</p>
	<p class="pnoall">
	<img border="0" src="images/text_events.gif"></p>
	<p class="pnoall">Predefined update value strategies - <b>POLICY_UPDATE</b>,
	<b>POLICY_NEVER</b>, <b>POLICY_ON_REQUEST</b> and <b>POLICY_CONVERT</b> - 
	may be selected or a custom strategy class may chosen.</p>
	<p class="pnoall">
	<img border="0" src="images/update_value_strategy1.gif" align="top">&nbsp;&nbsp;&nbsp;&nbsp;
	<img border="0" src="images/update_value_strategy2.gif"></p>
	<p class="pnoall">When binding to a <b>selection</b> object, the entire 
	object may be bound to using the <b>Selection as object</b> radio button or 
	one of its fields may be bound to using the <b>Part of selection</b> radio 
	button. When <b>Part of selection</b> is chosen, the type of the selection 
	should be specified in the <b>Class</b> field. A property specific to the 
	specified class may then be specified.</p>
	<p class="pnoall">
	<img border="0" src="images/bind_properties_swt2.gif"></p>
	<p class="pnoall">
	If the <b>Strategy Properties</b> section is expanded for either the <b>
	Target</b> or <b>Model</b>, validators (AfterConvert, AfterGet and BeforeSet) 
	and converters can be specified.</p>
	<p class="pnoall">
	<img src="images/edit_binding_strategy_properties.gif" alt=""></p>
	<p class="pnoall">
	If necessary, the resulting binding object can be assigned to a field. This 
	can be useful when you need to bind to the <b>validationStatus</b> of the 
	binding itself.</p>
	<p class="pnoall">
	<img border="0" src="images/assign_binding_to_field.gif">&nbsp;&nbsp;
	<img border="0" src="images/validation_status.gif" align="top"></p>
	<h2>Existing SWT Bindings</h2>
	<p class="pnoall">At the top of the page, existing <b>Bound Properties</b> 
	are listed. The <b>Target</b> and <b>Model</b> are shown as well as the <b>
	Target Strategy</b> and the <b>Model Strategy</b>. </p>
	<p class="pnoall">
	<img border="0" src="images/bound_properties_swt.gif"></p>
	<p class="pnoall">Clicking the
	<img border="0" src="images/data_binding_edit_button.gif" align="absbottom">
	<b>Edit</b> button or <b>Edit</b> menu opens the <b>Edit Binding</b> dialog 
	where the update strategies may be modified.</p>
	<p class="pnoall">
	<img border="0" src="images/edit_binding_swt1.gif" align="top" width="326" height="294">&nbsp;&nbsp;&nbsp;&nbsp;
	<img border="0" src="images/edit_binding_swt2.gif"></p>
	<p class="pnoall">The
	<img border="0" src="images/data_binding_delete_button.gif" align="absbottom">
	<b>Delete</b> button or <b>Delete</b> menu is used to delete the selected 
	bound property while the
	<img border="0" src="images/data_binding_delete_all_button.gif" align="absbottom">
	<b>Delete All</b> button or <b>Delete All</b> menu is used to delete all of 
	the bound properties.</p>
	<p class="pnoall">The
	<img border="0" src="images/data_binding_move_up_button.gif" align="absbottom">
	<b>Move Up</b> and
	<img border="0" src="images/data_binding_move_down_button.gif" align="absbottom">
	<b>Move Down</b> buttons and menus are used to change the order of the 
	bindings while the
	<img border="0" src="images/data_binding_goto_definition_button.gif" align="absbottom">
	<b>Goto Definition</b> button and menu are used to jump to the generated 
	code for the binding.</p>
	<h2>
	Source</h2>
		<p class="pnoall">As bindings are created or edited on the Bindings tab, 
		the necessary data binding 
		code is generated which may then be seen in the <b>Source</b> view. An <b>initDataBindings()</b> 
		method is created, if it does not already exist and a call to that 
		method is added to the end of the widget creation process.</p>
	<p class="pnoall">Within the <b>initDataBindings()</b> method, any needed 
	observables are created first followed by the creation of the <b>Data 
	Binding Context</b>. Simple SWT data bindings are then created using the new 
	context followed by any JFace content providers, list providers and inputs 
	that are needed.</p>
	<p class="pnoall">
	<img border="0" src="images/data_binding_source.gif"></p>
	<p class="pnoall"><i><b>Warning: </b>do not edit the <b>initDataBinding()</b> 
	method by hand (without carefully matching the code generation pattern used 
	by the tool) as it will be regenerated in its entirety any time 
	the tool 
	needs to add, remove or update a data binding.</i></p>
          </body>
</html>